Supported input types for OSL nodes¶

Conceptually an OSL shader corresponds to a node in our node system. Input parameters will show up as input pins on the OSL texture node. There is a single output parameter corresponding to the output value of the node.

The types in OSL code correspond to the following Octane pin types:

OSL type	Octane pin type
`color`	Texture
`point`	Projection (UV, spherical, cylindrical…) or 3D float (X, Y, Z), see below
`vector`, `normal`	3D float
`matrix`	Transform
`float`	Float
`int`	Int or Bool (depending on meta data)
`float[N]`, `int[N]`, up to 3 elements	1D, 2D or 3D float or int
`string`	Filename, String or Enum. See String handling.

Array inputs other than the ones mentioned above are not supported.

If an input has a constant value as default value, the corresponding input pin will have that value as default value as well.

For disconnected pins Octane will look for vertex attributes with a matching name.

Built-in inputs¶

If an input is decorated with [[int builtin = 1]] Octane will not create an input pin for this parameter. Instead the value comes from Octane itself.

These are the currently available built-in input values:

Parameter	meaning
`int isNormalMap`	`1` if the output of this OSL shader is interpreted as a normal map, `0` otherwise.
`int isEnvironmentMap`	`1` while an environment map is being evaluated, `0` otherwise.
`int flipU`	`1` in contexts where Octane will generate mirrored U coordinates (environment maps, and distributions on lights).

If the current version doesn’t provide this parameter the provided initializer is used. Built-ins never fall back to vertex attributes.

Input meta data¶

OSL supports shader metadata to encode hints about the meaning of input parameters. Octane will use some of this metadata to change the appearance or ranges of input pins.

    float FocalLength = 1
      [[ string label = "Focal length",
         float min = 0.1,
         float max = 1000,
         float sliderexponent = 4]],

All inputs:¶

Metadata	meaning
`string widget`	Choose which type of widget to use. The meaning depends on the input type, see below.
`string label`	Override the name shown in the node inspector (normally the variable name is shown)
`string help`	Provides a tool tip for the pin when you hover your mouse over the pin
`string page`	Can be used to group pins into categories

Color inputs:¶

Metadata	meaning
`string widget = "number"`	Use a float texture instead of an RGB spectrum as default input type.
`string variant = "normalMap"`	Evaluate the nodes connected to this input as a normal map
`string variant = "asOutput"`	Evaluate as normal map only if the output of this shader is evaluated as a normal map

Numeric inputs: int and float:¶

All numeric inputs support the following metadata:

Metadata	meaning
`float/int min, max`	Specify the minimum and maximum values for a float or int input (note that there's no guarantee that the actual value for the variable in the shader is inside these bounds)
`float/int slidermin, slidermax`	Allows you to specify a more narrow value range for the sliders. Users may still enter values outside this range (but within min / max) using right mouse button drag, and by typing a value.
`float/int sensitivity`	Allows you to specify the steps for a float/int type variable
`float/int sliderexponent`	sets up the skew factor for the slider. In Octane, only linear (sliderexponent == 1) and logarithmic (sliderexponent > 1) are supported

Int inputs:¶

Metadata	meaning
`string widget = "checkBox"`	show a checkbox instead of a slider. The input value will be 0 or 1.
`string widget = "boolean"`	synonym for “checkBox”
`string widget = "mapper"` `string options`	Use a combo box. Options are separated by pipe characters, the keys and value by a colon. Eg. `"option one:1\|option two:2\|option three:3"`

Vector inputs:¶

For vector inputs you may specify a sun direction node by default. Users can switch between plain 3D float inputs and sun direction inputs if desired.

Metadata	meaning
`string widget = "sunDirection"`	Show a sun direction node by default

Point inputs¶

For point inputs, Octane may create a projection pin or a 3D float pin.

You can explicitly choose a type by setting inputType:

Metada	Octane pin type
`string inputType = "projection"`	Create a projection pin
`string inputType = "float"`	Create a 3D float pin

To specify a default projection type for projection input, use "projection:<type>". The type names follow the API names for the node type IDs.

Type name	Default type	Type ID
`"box"`	Box	`NT_PROJ_BOX`
`"colorToUvw"`	Color to UVW	`NT_PROJ_COLOR_TO_UVW`
`"cylindrical"`	Cylindrical	`NT_PROJ_CYLINDRICAL`
`"distortedMeshUv"`	Distorted mesh UV	`NT_PROJ_DISTORTED_MESH_UV`
`"instancePosition"`	Instance position	`NT_PROJ_INSTANCE_POSITION`
`"linear"`	XYZ to UVW	`NT_PROJ_LINEAR`
`"matcap"`	MatCap	`NT_PROJ_MATCAP`
`"osl"`	OSL projection node	`NT_PROJ_OSL`
`"oslUv"`	OSL defined UV coordinates	`NT_PROJ_OSL_UV`
`"perspective"`	Perspective	`NT_PROJ_PERSPECTIVE`
`"samplePosition"`	Sample pos. to UV	`NT_PROJ_SAMPLE_POSITION`
`"spherical"`	Spherical	`NT_PROJ_SPHERICAL`
`"triplanar"`	Triplanar mapping	`NT_PROJ_TRIPLANAR`
`"uvw"`	Mesh UV	`NT_PROJ_UVW`

Otherwise, the type depends on the initializer:

Initializer	Octane pin type
`point p = P`	Create a projection pin, with XYZ to UVW as default node type
`point p = point(u, v, 0)`	Create a projection pin, with Mesh UV as default node type
`point p = point(1, 2, 3)` (or any other constant value)	Create a 3D float pin

For other cases the behavior may change between Octane versions.

For projection inputs, you can also choose between the default behavior and the image projection behavior. The latter is enabled by setting the variant to:

Metadata	meaning
`string variant = "image"`	use the image projection behavior

Matrix inputs¶

Metadata	meaning
`int dim`	set to either 2 or 3, specifies if the matrix should be shown as a 2D or 3D transform

Matrix inputs can optionally specify that they are UVW transforms via the type metadata attribute. Inputs of string type = "uvw" will additionally be transformed by any parent UVW transform nodes.

Metadata	meaning
`string type = "uvw"`	matrices from parent `UVW transform` nodes will be premultiplied to this input

String inputs¶

Metadata	meaning
`string widget = "popup"` `string options`	Use a combo box. Options are separated by pipe characters. Eg. `"option one\|option two\|option three"`
`int editable`	If 1, this allows entering string values in a combo box which are not in the list of options

Info

File name inputs are always displayed as a file input, regardless of any given metadata.

Last update: October 2, 2023